<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.29
     from oil.tnf on 19 December 2010 -->

<TITLE>Oil Reference Manual - OIL's Support Library</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000" BACKGROUND="gifs/bg.gif">
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0" VALIGN=BOTTOM>
<TR VALIGN=BOTTOM>
<TD WIDTH="160" VALIGN=BOTTOM>
<A HREF="http://eli-project.sourceforge.net/">
<IMG SRC="gifs/elilogo.gif" BORDER=0>
</A>&nbsp;
</TD>
<TD WIDTH="25" VALIGN=BOTTOM>
<img src="gifs/empty.gif" WIDTH=25 HEIGHT=25>
</TD>
<TD ALIGN=LEFT WIDTH="475" VALIGN=BOTTOM>
<A HREF="index.html"><IMG SRC="gifs/title.png" BORDER=0></A>
</TD>
<!-- |DELETE FOR SOURCEFORGE LOGO|
<TD>
<a href="http://sourceforge.net/projects/eli-project">
<img
  src="http://sflogo.sourceforge.net/sflogo.php?group_id=70447&amp;type=13"
  width="120" height="30"
  alt="Get Eli: Translator Construction Made Easy at SourceForge.net.
    Fast, secure and Free Open Source software downloads"/>
</a>
</TD>
|DELETE FOR SOURCEFORGE LOGO| -->
</TR>
</TABLE>

<HR size=1 noshade width=785 align=left>
<TABLE BORDER=0 CELLSPACING=2 CELLPADDING=0>
<TR>
<TD VALIGN=TOP WIDTH="160">
<h4>General Information</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="index.html">Eli: Translator Construction Made Easy</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gindex_1.html#SEC1">Global Index</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="faq_toc.html" >Frequently Asked Questions</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Tutorials</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="EliRefCard_toc.html">Quick Reference Card</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="novice_toc.html">Guide For new Eli Users</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="news_toc.html">Release Notes of Eli</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="nametutorial_toc.html">Tutorial on Name Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="typetutorial_toc.html">Tutorial on Type Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Reference Manuals</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ui_toc.html">User Interface</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="pp_toc.html">Eli products and parameters</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lidoref_toc.html">LIDO Reference Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Libraries</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lib_toc.html">Eli library routines</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="modlib_toc.html">Specification Module Library</a></td></tr>
</table>

<h4>Translation Tasks</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lex_toc.html">Lexical analysis specification</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="syntax_toc.html">Syntactic Analysis Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="comptrees_toc.html">Computation in Trees</a></td></tr>
</table>

<h4>Tools</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lcl_toc.html">LIGA Control Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="show_toc.html">Debugging Information for LIDO</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gorto_toc.html">Graphical ORder TOol</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="fw_toc.html">FunnelWeb User's Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ptg_toc.html">Pattern-based Text Generator</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="deftbl_toc.html">Property Definition Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="oil_toc.html">Operator Identification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="tp_toc.html">Tree Grammar Specification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="clp_toc.html">Command Line Processing</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="cola_toc.html">COLA Options Reference Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="idem_toc.html">Generating Unparsing Code</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="mon_toc.html">Monitoring a Processor's Execution</a> </td></tr>
</table>

<h4>Administration</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="sysadmin_toc.html">System Administration Guide</a> </td></tr>
</table>

<HR WIDTH="100%">
<A HREF="mailto:eli-project-users@lists.sourceforge.net">
<IMG SRC="gifs/button_mail.gif" BORDER=0 ALIGN="left"></A>
<A HREF="index.html"><IMG SRC="gifs/home.gif" BORDER=0 ALIGN="right"></A>

</TD>
<TD VALIGN=TOP WIDTH="25"><img src="gifs/empty.gif" WIDTH=25 HEIGHT=25></TD>

<TD VALIGN=TOP WIDTH="600">
<H1>Oil Reference Manual</H1>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_3.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_5.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
<A NAME="IDX32"></A>
<A NAME="IDX33"></A>
<A NAME="IDX34"></A>
<H1><A NAME="SEC18" HREF="oil_toc.html#SEC18">OIL's Support Library</A></H1>
<P>
The library functions are grouped according to classes of functions.  
Within each class a C definition of the function is 
presented, followed by a brief description of the semantics of the function.
<P>
The next section describes the five C types used and defined by the
library. These types are defined entirely by the functions in OIL's
library.
<P>
The follow-on section describes operator identification using
<EM>set of possible types</EM> which is the most general identification
method supported by OIL.
<P>
Should a call to an OIL function for operator identification or coercion
sequence construction fail, special values are returned.
Functions are supplied to test for these special values allowing
production of error messages for these error cases.
<P>
Besides operator identification using set of possible types, there is
also a simpler identification algorithm which is strictly bottom up.  It
is useful when the full power of OIL is not necessary and the efficiency
of a one pass algorithm can be utilized.
<P>
Looking at an operator's type signature is fundamental to propagating
the constraints of an operator's type signature out from the node it
labels. OIL supplies a function to examine any given operator's
function signature,
<P>
Coercion sequences are fundamental to most uses of OIL and constructing
and examining coercion sequences is critical to examining them for code
generation purposes.
<P>
Creating instances of specified classes.
OIL's <EM>CLASS</EM> construct allows for easy support of most type
constructors.  OIL allows a type constructor to be specified and then
instantiated to create a type which conforms to the specification of the
<EM>CLASS</EM>. 
<P>
Names are an enumeration of the identifiers in the specification for
easy comparisons.  When a class is instantiated all its operators have
new unique signatures based on the created type, but the names of
corresponding operators are the same as those used in the specification
of the class operator.
<P>
Construction of types, operators, identifications and classes can be
performed by the library functions.  Thus should a particular
application need to build and define a unique class, coercion or any OIL
object it can be done during the compilation using these functions.
<P>
<H2><A NAME="SEC19" HREF="oil_toc.html#SEC19">Library Types</A></H2>
The semantics of the functions are described in terms of the basic types
understood by OIL.
<DL COMPACT>
<DT><CODE>tOilType</CODE>
<DD>This type is associated with the 
identifiers defined as (<EM>type</EM>) in the OIL specification and
represents type denotations. It is used to define function signatures
for operators and thus the coercion graph.
<P>
<DT><CODE>tOilOp</CODE>
<DD>This type is associated with 
the identifiers defined as (<EM>operator</EM>) in the OIL specification.
An element of this type can have associated with it either a function
signature or a list of identifiable operators.  All coercions are
operators. 
<P>
<DT><CODE>tOilTypeSet</CODE>
<DD>Is a private type of the OIL library functions which 
represents a set of type denotations and represents the <EM>set of
possible types</EM> concept.
<A NAME="IDX36"></A>
<A NAME="IDX35"></A>
<P>
<DT><CODE>tOilClass</CODE>
<DD>This type is associated with identifiers defined as (<EM>class</EM>) in
the OIL specification and identifies the set of operators and coercions
defined for that class.  It is used as the handle for instantiating a
class.  The instantiation operation creates a new object of type:
<CODE>tOilType</CODE> and adds new instances of the operators and coercions
defined for the class.
<P>
<DT><CODE>tOilCoercionSeq</CODE>
<DD>This type 
represents a sequence of coercion operators which will transform 
a value of one type into a desired type.  The coercions sequence may be
empty or of an arbitrary length.  Each element in a coercion sequence is
a coercion operator.
<A NAME="IDX37"></A>
</DL>
<P>
There is one other type which is important for use of the ADT and that
is the <EM>name</EM> of a class, type or operator.  A <EM>name</EM> is
represented as a definition table key
(see  <A HREF="deftbl_1.html#SEC2">The Definition Table Module of Definition Table</A>)
and each identifier in the OIL specification
has a unique <EM>name</EM> associated with it.  This allows a class
operator to be treated the same regardless of its arguments.  But since
the argument signature of an instantiated class operator will refer to
the types used to instantiate the class, the type specific information
can be referenced as needed.
<P>
<H2><A NAME="SEC20" HREF="oil_toc.html#SEC20">Set of Possible Types</A></H2>
<A NAME="IDX38"></A>
<A NAME="IDX39"></A>
<A NAME="IDX40"></A>
<P>
The functions <CODE>OilIdResultTS*</CODE> 
identify the set of possible result types given the operator
indication (<EM>oi</EM>)
and the set of possible result types (<EM>ats*</EM>) for each operand.
<P>
The set of types (<EM>tOilTypeSet</EM>) returned describes the the union of the
result types of any of the operators which can be identified by (<EM>oi</EM>)
with any combination of argument types selected by the argument type sets,
(<EM>at*</EM>.)
Also in this set are types which can be reached from identified operators by 
means of a coercion sequence.
<P>
<A NAME="IDX41"></A>
<A NAME="IDX42"></A>
<A NAME="IDX43"></A>
<PRE>
tOilTypeSet OilIdResultTS1( oi:tOilOp, ats:tOilTypeSet ); 
tOilTypeSet OilIdResultTS2( oi:tOilOp, ats1,ats2:tOilTypeSet ); 
tOilTypeSet OilIdResultTS3( oi:tOilOp, ats1,ats2,ats3:tOilTypeSet ); 
</PRE>
<P>
The functions <CODE>OilIdOpTS*</CODE> identify an operator given 
the operator indication (<EM>oi</EM>), 
the result type (<EM>rt</EM>) and
the sets of possible argument types (<EM>ats*</EM>.)
<A NAME="IDX45"></A>
<A NAME="IDX44"></A>
<P>
<A NAME="IDX46"></A>
<A NAME="IDX47"></A>
<A NAME="IDX48"></A>
<PRE>
tOilOp OilIdOpTS1( rt:tOilType, oi:tOilOp, ats:tOilTypeSet ); 
tOilOp OilIdOpTS2( rt:tOilType, oi:tOilOp, ats1,ats2:tOilTypeSet ); 
tOilOp OilIdOpTS3( rt:tOilType, oi:tOilOp, ats1,ats2,ats3:tOilTypeSet ); 
</PRE>
<P>
Suppose that an operator indication can identify only a single operator,
but it is used in an inappropriate context for that operator.
Functions <CODE>OilIdOpTS*</CODE> will return an invalid operator in that case.
In many situations, however, it is preferable to return the one possible
operator and report errors in the context.
The function <CODE>OilNoOverload</CODE> is used in these situations.
<P>
<A NAME="IDX49"></A>
<PRE>
tOilOp OilNoOverload( oi:tOilOp, OilIdOpTS*( ... ));
</PRE>
<P>
The function <CODE>OilTypeToSet</CODE> 
constructs a set of types from a given type denotation.
<A NAME="IDX50"></A>
The set of types returned contains <EM>t</EM> and
all the type denotations which  can be reached from <EM>t</EM>
by any sequence of coercion operators.
<A NAME="IDX51"></A>
<P>
<PRE>
tOilTypeSet OilTypeToSet( t:tOilType ); 
<A NAME="IDX52"></A>
</PRE>
<P>
The function <CODE>OilSelectTypeFromTS</CODE>
selects a type from a given set of types.  The type selected
is the type which is both in the set <EM>ts</EM> and can be coerced to all the 
types in the set.
<A NAME="IDX54"></A>
<A NAME="IDX53"></A>
<P>
<PRE>
tOilType OilSelectTypeFromTS( ts:tOilTypeSet ); 
<A NAME="IDX55"></A>
</PRE>
<P>
The following equation is true for any type <CODE>t</CODE>:
<PRE>
OilSelectTypeFromTS( OilTypeToSet( t ) ) = t
</PRE>
<P>
The function <CODE>OilBalance</CODE>
selects a type which can be coerced to all the elements
which sets <EM>ts1</EM> and <EM>ts2</EM>  have in common.  This operation
corresponds with function of type balancing in typed expression analysis
from compiler and programming language theory.
<A NAME="IDX57"></A>
<A NAME="IDX56"></A>
<P>
<PRE>
tOilType OilBalance( ts1,ts2:tOilTypeSet ); 
<A NAME="IDX58"></A>
</PRE>
The following is true for all type sets <CODE>ts1</CODE> and <CODE>ts2</CODE>:
<PRE>
OilBalance( ts1,ts2 ) = OilSelectTypeFromTS( ts1 AND ts2 )
</PRE>
<P>
One other important operation on sets is a test for set membership.
This operation is performed on a type set by the function
<CODE>OilSetIncludes</CODE>, which returns true if the set <CODE>s</CODE> includes
the type <CODE>t</CODE>.
<PRE>
int OilSetIncludes( s:tOilTypeSet, t:tOilType );
<A NAME="IDX59"></A>
</PRE>
<P>
<CODE>OilSetIncludes</CODE> will be the usual mechanism for testing if a
expression can be coerced to a particular type.  The expression's set of
possible types is calculated and <CODE>OilSetIncludes</CODE> is used to check
if the type in question is in the set of possible types.
<P>
<A NAME="IDX60"></A>
<H2><A NAME="SEC21" HREF="oil_toc.html#SEC21">Validating operator identification</A></H2>
<P>
The function <CODE>OilIsValidOp</CODE> validates that a given value denotes
a valid operator.  
<A NAME="IDX61"></A>
Since any operator identification operation will return some
operator indication, we need to validate that the operator identified
was not the catchall <EM>illegal operator</EM>.
<A NAME="IDX62"></A>
<P>
<PRE>
int OilIsValidOp( op: tOilOp ); 
<A NAME="IDX63"></A>
</PRE>
<P>
<H2><A NAME="SEC22" HREF="oil_toc.html#SEC22">Simpler operator identification</A></H2>
<P>
The function <CODE>OilIdOp*</CODE> can 
identify the operator associated with the indication (<EM>oi</EM>)
which has an argument type to which (<EM>at</EM>) can be coerced.
In general these are less powerful than the `set of result type'
operators,
but for simple languages they are both faster and easier to use.  You can
probably use these if you can identify the correct operator from the
the types of the operands alone without regard to the  context.
<P>
<A NAME="IDX64"></A>
<A NAME="IDX65"></A>
<A NAME="IDX66"></A>
<PRE>
tOilOp OilIdOp1( oi: tOilOp, at: tOilType ); 
tOilOp OilIdOp2( oi: tOilOp, at1,at2: tOilType ); 
tOilOp OilIdOp3( oi: tOilOp, at1,at2,at3: tOilType ); 
</PRE>
<P>
<H2><A NAME="SEC23" HREF="oil_toc.html#SEC23">Looking at an operator's type signature</A></H2>
The function <CODE>OilGetArgType</CODE> allows us to get the type of the
n'th argument (<EM>arg</EM>) of an operator(<EM>op</EM>.)  The 0'th argument
returns the result type from the function signature.
<A NAME="IDX68"></A>
<A NAME="IDX69"></A>
<A NAME="IDX70"></A>
<A NAME="IDX67"></A>
<P>
<PRE>
tOilType OilGetArgType( op:tOilOp, arg:int ); 
<A NAME="IDX71"></A>
</PRE>
<P>
<A NAME="IDX72"></A>
<A NAME="IDX73"></A>
<H2><A NAME="SEC24" HREF="oil_toc.html#SEC24">Coercion sequences</A></H2>
<P>
The function <CODE>OilCoerce</CODE>
allows us to construct a sequence of coercion operators
from type <EM>t1</EM> to <EM>t2</EM>.  
The first operator in the sequence (see <CODE>OilHeadCS</CODE> below)
will have a result type of <EM>t2</EM>.  The last operator in the 
sequence will have a source type of <EM>t1</EM>. 
<A NAME="IDX75"></A>
<A NAME="IDX74"></A>
<CODE>OilCoerce</CODE> will always return a coercion sequence. But if there is no
valid coercion sequence between the types then the catchall 
<EM>error coercion sequence</EM> is produced.
<A NAME="IDX77"></A>
<A NAME="IDX76"></A>
<P>
<PRE>
tOilCoercionSeq OilCoerce(  t1,t2:tOilType ); 
<A NAME="IDX78"></A>
</PRE>
<P>
These operations on coercion sequences (<CODE>tOilCoercionSeq</CODE>) allow us to
step through a coercion sequence and perform an action for each
operator in the sequence.
<P>
The function <CODE>OilEmptyCS</CODE> will test a coercion sequence to see if it
is empty.  The result will be true is the argument is empty and false otherwise.
<A NAME="IDX80"></A>
<A NAME="IDX79"></A>
<P>
The function <CODE>OilHeadCS</CODE> returns the first operator in the sequence.
The operator returned by <CODE>OilHeadCS</CODE> will have been defined by a 
coercion statement. Or it will be the error operator in the case of an
<EM>error coercion sequence</EM>.
<A NAME="IDX82"></A>
<A NAME="IDX81"></A>
<P>
The function <CODE>OilTailCS</CODE> returns the rest of the sequence once the first
operator in the sequence is removed. 
<A NAME="IDX84"></A>
<A NAME="IDX83"></A>
<P>
<A NAME="IDX85"></A>
<A NAME="IDX86"></A>
<A NAME="IDX87"></A>
<PRE>
int OilEmptyCS( cs: tOilCoercionSeq ); 
tOilOp OilHeadCS( cs: tOilCoercionSeq ); 
tOilCoercionSeq OilTailCS( cs: tOilCoercionSeq ); 
</PRE>
<P>
The function <CODE>OilIsValidCS</CODE>
allows us to validate a coercion sequence.  It is crucial
to detect invalid typing for a subexpression since every call to 
<CODE>OilCoerce</CODE> will return a coercion sequence and we need to know if
the sequence returned was the catchall <DFN>error coercion</DFN>.
<A NAME="IDX89"></A>
<A NAME="IDX88"></A>
<P>
<PRE>
int OilIsValidCS( cs: tOilCoercionSeq ); 
<A NAME="IDX90"></A>
</PRE>
<P>
<H2><A NAME="SEC25" HREF="oil_toc.html#SEC25">Instantiate Classes</A></H2>
<P>
When a class is instantiated a new type is created and the set of
operators and coercions defined for that class are created using the
created class and the types indicated by the parameters to build the
actual function signatures for the created operators.  The `is coercible
to' relation is enhanced by all the coercions defined by the
instantiation. 
<P>
Classes can be instantiated by calling one of the functions:
<P>
<A NAME="IDX91"></A>
<A NAME="IDX92"></A>
<A NAME="IDX93"></A>
<PRE>
tOilType OilClassInst0( c:tOilClass, n:DefTableKey ); 
tOilType OilClassInst1( c:tOilClass, n:DefTableKey, at:tOilType ); 
tOilType OilClassInst2( c:tOilClass, n:DefTableKey, at1,at2:tOilType ); 
</PRE>
<P>
Constraints:
<P>
The number of parameters defined for the class must match the number of
types supplied as arguments.
<P>
<H2><A NAME="SEC26" HREF="oil_toc.html#SEC26">Name Functions</A></H2>
<A NAME="IDX94"></A>
<P>
Each type, operator and class has a <EM>name</EM> associated with it.
There is a function for retrieving the name associated with a specific
type during attribution:
<P>
<A NAME="IDX95"></A>
<A NAME="IDX96"></A>
<A NAME="IDX97"></A>
<PRE>
DefTableKey OilTypeName( t:tOilType );
DefTableKey OilOpName( op:tOilOp );
DefTableKey OilClassName( c:tOilClass );
</PRE>
<P>
If the identifier <CODE>MyType</CODE> is a type in a specification then the
C symbol <CODE>MyType</CODE> will have the value of
<CODE>OilTypeName(MyType)</CODE>.
<A NAME="IDX98"></A>
<P>
<H2><A NAME="SEC27" HREF="oil_toc.html#SEC27">Compile Time</A></H2>
<P>
The OIL library has all of the necessary functions for the construction
of OIL entities during the execution of the generated compiler.  This
capability allows the changing of the OIL schema in more detailed ways
than simply instantiating an already specified class.  The different
capabilities for modifying the schema are:
<DL COMPACT>
<DT><STRONG>Type Constructor</STRONG>
<DD>	A new type may be constructed without using Classes.
<DT><STRONG>Operator Constructor</STRONG>
<DD>	A new operator may be explicitly constructed with a given
signature(remember operators are use to represent indications also.)
<DT><STRONG>Signature Constructor</STRONG>
<DD>	An argument signature for an operator can be constructed from
types.
<DT><STRONG>Coercion Constructor</STRONG>
<DD>	A properly constructed operator can be declared to be a
coercion.
<DT><STRONG>Identification Constructor</STRONG>
<DD>	Any operator can be defined to `indicate' any other operator.
<DT><STRONG>Class Constructor</STRONG>
<DD>	Can be built from class operators and coercions.
</DL>
<P>
<H3><A NAME="SEC28" HREF="oil_toc.html#SEC28">Types</A></H3>
In addition to class instantiation, a new type may be constructed with the
function <CODE>OilNewType</CODE>.  Its only argument is the name to be associated
with the new type.
<PRE>
tOilType OilNewType( id:DefTableKey );
<A NAME="IDX99"></A>
</PRE>
<P>
<H3><A NAME="SEC29" HREF="oil_toc.html#SEC29">Operators</A></H3>
Constructing a new operator is a two step process, first a new argument
signature must be constructed and then a new operator with that signature
can be constructed using the function <CODE>OilNewOp</CODE>.  Besides the
argument signature, <CODE>OilNewOp</CODE> requires the name of the new
operator(<CODE>id</CODE>), and the cost of the new operator(<CODE>cost</CODE>.)
<PRE>
tOilOp OilNewOp(id:DefTableKey,sig:tOilArgSig,cost:int);
<A NAME="IDX100"></A>
</PRE>
<P>
<H3><A NAME="SEC30" HREF="oil_toc.html#SEC30">Argument Signatures</A></H3>
Argument signatures are built in two steps: an empty signature is
constructed with <CODE>OilNewArgSig</CODE> and then a type is pushed onto the
front of the signature using <CODE>OilAddArgSig</CODE>.
<A NAME="IDX101"></A>
<A NAME="IDX102"></A>
<A NAME="IDX103"></A>
<PRE>
tOilArgSig OilNewArgSig(dummy:int);
tOilArgSig OilAddArgSig( arg:tOilType, sig:tOilArgSig );
</PRE>
Note that by convention, the last type pushed onto the signature is the
result type of the created operator.
<P>
<H3><A NAME="SEC31" HREF="oil_toc.html#SEC31">Coercions</A></H3>
Any operator with an argument signature of length 2 can be a coercion by
simply applying <CODE>OilAddCoercion</CODE> on it.
<PRE>
int OilAddCoercion( op:tOilOp );
<A NAME="IDX104"></A>
</PRE>
<P>
Constraints
<P>
A check is not made that the signature is of length 2.
<P>
<H3><A NAME="SEC32" HREF="oil_toc.html#SEC32">Identifications</A></H3>
A relationship between an operator indication (<CODE>ind</CODE>) and an operator
(<CODE>op</CODE>) is established by simply
supplying them to the <CODE>OilAddIdentification</CODE> function.
<CODE>OilAddIdentification</CODE> returns the value of <CODE>op</CODE>.
<PRE>
tOilOp OilAddIdentification( ind, op:tOilOp );
<A NAME="IDX105"></A>
</PRE>
<P>
Constraints
<P>
A check is not made regarding the redundancy of the new identification
with respect to the existing schema.  You can have ambiguity of which
operator is identified by any given indication and operand signature.
OIL will choose the most recently declared, least cost identification.
<P>
<H3><A NAME="SEC33" HREF="oil_toc.html#SEC33">Classes</A></H3>
Classes are very complex entities and are constructed in stages.  First an
empty class in created using <CODE>OilNewClass</CODE>.  The argument <CODE>id</CODE>
specifies the name of the class and the argument <CODE>argNum</CODE> specifies
how many parameters the class has.
<PRE>
tOilClass OilNewClass(id:DefTableKey,argNum:int);
<A NAME="IDX106"></A>
</PRE>
<P>
To an existing class(<CODE>c</CODE>) we can add an operator with a given class
signature(<CODE>sig</CODE>) and given cost(<CODE>cost</CODE>) with the function
<CODE>OilAddClassOp</CODE>.
<PRE>
tOilClassOp OilAddClassOp(id:DefTableKey,sig:tOilClassArgSig,cost:int, c:tOilClass);
<A NAME="IDX107"></A>
</PRE>
<P>
With a class operator we can create an identification of an instantiated
class operator(<CODE>op</CODE>) by an existing operator(<CODE>ind</CODE>) with the
function <CODE>OilAddClassOpId</CODE>.
<PRE>
int OilAddClassOpId(ind:tOilOp,op:tOilClassOp);
<A NAME="IDX108"></A>
</PRE>
<P>
The function <CODE>OilAddClassCoercion</CODE> is used to 
define an existing class operator(<CODE>op</CODE>) to be a coercion.
<PRE>
int OilAddClassCoercion(op:tOilClassOp);
<A NAME="IDX109"></A>
</PRE>
<P>
Building a class argument signature is similar to constructing a simple
argument signature but it is complicated by the fact that a class argument needs
to be described in terms of a parameter binding. A class argument's
parameter binding determines the value of the parameter when the class
is instantiated. Like simple signatures we first build an empty class
signature and then push arguments onto it.  An empty class signature is
created with <CODE>OilNewClassSigArg</CODE> and an argument description is added
with <CODE>OilAddClassSigArg</CODE>. 
<PRE>
tOilClassArgSig OilNewClassSigArg(dummy:int);
<A NAME="IDX110"></A>
</PRE>
<PRE>
tOilClassArgSig OilAddClassSigArg(
			    td:tOilClassSigArgDesc,
			    st:tOilType,
			    pi:int,
			    cs:tOilClassArgSig
			  );
<A NAME="IDX111"></A>
</PRE>
The extra arguments to <CODE>OilAddClassSigArg</CODE> describe the possible
bindings which will instantiate the class signature.
<DL COMPACT>
<DT><CODE>td</CODE>
<DD>Can be <CODE>eClassRef</CODE> to indicate that a reference to the created type
replaces this argument, <CODE>eParamRef</CODE> to indicate that one of the
parameters to the class instantiation will replace this argument or
<CODE>eSpecTypeRef</CODE> to indicate 
that a specific type will replace this argument.
<DT><CODE>st</CODE>
<DD>Specifies which explicit type will replace this argument.
<DT><CODE>pi</CODE>
<DD>Selects which parameter of the class instantiation will replace this
argument. 
</DL>
<P>
<HR size=1 noshade width=600 align=left>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_3.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_5.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="oil_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
</TD>
</TR>
</TABLE>

</BODY></HTML>
